Simulation sequences

Sequence monad

data Sequence a (Simantics/Sequences)

Sequence a is a plan of some operations that may happen during the simulation and may take some (simulation) time. A sequence is initiated at a specific time and it may either finish at a specific time or operate forever. If it completes, it retuns a value of type a.

Sequence :: ((a -> <Action,Proc> ()) -> <Action,Proc> ()) -> Sequence a (Simantics/Sequences)

We call the sequence instantious, if its duration is zero, i.e, the sequence finishes immediately after started.

A cooking recipe is an example of a sequence in the real world. Its return value could be for example the success indication of the cooking process.

instance Monad Sequence

In order to build complex sequences from simple primitives, the sequences implement Monad operations and its laws. These are

return :: Monad a => b -> a b (Prelude)

Inject a value into the monadic type.

(>>=) :: Monad a => a b -> (b -> a c) -> a c (Prelude)

Sequentially compose two actions, passing any value produced by the first as an argument to the second.

The sequence return v has zero duration, it does not modify the simulator state and returns v. The sequence seqA >>= f is a sequence that first behaves like seqA, and when it has completed and returned a value resultA, continues like the sequence f resultA. In other words, (>>=) concatenates two sequences and the behavior of the latter sequence may depend on the return value of the former sequence.

(>>) :: Monad a => a b -> a c -> a c (Prelude)

Sequentially compose two actions, discarding any value produced by the first, like sequencing operators (such as the semicolon) in imperative languages."

fmap :: Functor a => (b -> c) -> a b -> a c (Prelude)

Lifts a pure function to the given functor.

join :: Monad a => a (a b) -> a b (Prelude)

The join function is the conventional monad join operator. It removes one level of monadic structure.

For lists, join concatenates a list of lists:

join [[1,2], [3,4]] = [1, 2, 3, 4]
sequence :: FunctorM a => Monad b => a (b c) -> b (a c) (Prelude)

Evaluate each action in the sequence from left to right, and collect the results.

repeatForever :: Monad a => a b -> a c (Prelude)

Sequences the given monadic value infinitely:

repeatForever m = m >> m >> m >> ...

These operations are derived from the primitive monad operations. The sequence seqA >> seqB behaves first like seqA and when it has finished it continues like seqB. The sequence fmap f seq maps the result of the sequence seq by the function f. The sequence join seq first behaves like the sequence seq and then like the sequence seq returned. The sequence sequence seqs executes every sequence in the container seqs sequentially. The container can be for example list or Maybe. The sequence repeatForever seq repeats the sequence seq forever, never returning.

Actions

effect Action

<Action> a is an instantious operation happening in the simulator and returning a value of type a. It can be a pure reading operation, but may also modify the simulator state. The duration of an action is always zero.

time :: <Action> Double (Simantics/Sequences)

Gives the current simulation time.

getVar :: Serializable a => String -> <Action> a (Simantics/Sequences)

Returns the current value of a variable

setVar :: Serializable a => String -> a -> <Action> () (Simantics/Sequences)

Sets the value of a variable

execute :: <Action,Proc> a -> Sequence a (Simantics/Sequences)

The sequence execute action is an instantious sequence that executes the operation action in the simulator.

Multiple actions happening at the same time may be written either as separate sequences:

mdo execute (setVar "SP1#SP_VALUE" 13)
    execute (setVar "SP2#SP_VALUE" 14)

or as one sequence with more complicated action:

execute do
    setVar "SP1#SP_VALUE" 13
    setVar "SP2#SP_VALUE" 14

Controlling time

waitStep :: Sequence () (Simantics/Sequences)

The sequence waitStep waits that the simulator takes one simulation step. It is a primitive mechanism that can be used to implement other events by inspecting the simulator state after each time step.

waitUntil :: Double -> Sequence () (Simantics/Sequences)

The sequence waitUntil time waits until the simulation time is at least the given time.

wait :: Double -> Sequence () (Simantics/Sequences)

The sequence wait duration waits that duration seconds elapses from the current simulation time.

waitCondition :: <Action,Proc> Boolean -> Sequence () (Simantics/Sequences)

The sequence waitCondition condition waits until the condition is satisfied.

Parallel execution

fork :: Sequence a -> Sequence () (Simantics/Sequences)

The sequence fork seq is an instantious sequence that creates a new sequence thread behaving like the sequence seq.

halt :: Sequence a (Simantics/Sequences)

The sequence halt ends the current sequence thread and the sequence .

stop :: Sequence a (Simantics/Sequences)

The sequence stop stops all sequence threads, stopping the simulation completely.

Semantics

Although the simulation sequences support threading, its semantics is deterministic. This is ensured by the following equivalences:

halt >> seqA                                       = halt
stop >> seqA                                       = stop
fork (execute actionA >> seqA) >> seqB             = execute actionA >> fork seqA >> seqB
fork (waitStep >> seqA) >> execute actionB >> seqB = execute actionB >> fork seqA >> seqB
fork (waitStep >> seqA) >> waitStep >> seqB        = waitStep >> fork seqA >> seqB
fork halt >> seqB                                  = seqB
fork seqA >> halt                                  = seqA
fork stop >> seqB                                  = stop
fork (waitStep >> seqA) >> stop                    = stop

Using the sequences with Apros

In order to run the sequence in Apros, function

has been defined. It starts automatically starts simulation, if it is not yet running. When all simulation threads are halted or some thread calls stop the simulation is stopped. The sequence can also aborted by aborting the SCL-command (red box in the upper right corner of the console).

import "Apros/Sequences"
runSequence mdo
    fork $ repeatForever mdo
        waitCondition (getVar "TA01#TA11_LIQ_LEVEL" >= 3.0)
        execute (setVar "BP01#PU11_SPEED_SET_POINT" 0.0)
        wait 1
    fork $ repeatForever mdo
        waitCondition (getVar "TA01#TA11_LIQ_LEVEL" <= 2.0)
        execute (setVar "BP01#PU11_SPEED_SET_POINT" 100.0)
        wait 1

Examples

Check that pressure of the point stays below a certain value:

fork mdo waitCondition (getVar "POINT1#PO11_PRESSURE" > 120.0)
         execute (print "Error! Error!")
         stop

Check that the valve is closed 10 seconds after the operator presses the button:

fork $ repeatForever mdo
    waitCondition (getVar "BUTTON#BINARY_VALUE")
    fork mdo
        wait 10
        valvePos <- execute (getVar "VALVE#VA11_POSITION")
        if valvePos == 0
        then return () // OK
        else mdo
            execute (print "Error! Error!")
            stop